Are these special field names part of the YAML spec?
Would an alternative be to have a SubModel which has extra="allow"?

Are these special field names part of the YAML spec? Would an alternative be to have a SubModel which has extra="allow"?

@phil65 Thanks for the review and these thoughtful questions! Let me address them:

About the special field names

These prefixes (., _, x-) are not part of the YAML spec itself. They are naming conventions we chose to support the following use cases:

1. YAML Anchors (primary use case): Users want to define reusable configuration fragments in YAML, e.g.:

   .shared_model: &default_model
     type: native
     model: "openai:gpt-4o"
   
   agents:
     coder: *default_model
       name: coder

   The .anchor definitions are essentially placeholders. After the YAML loader resolves the anchors, these fields effectively disappear (anchors are expanded at reference points), so they won't appear in the final validated object.

2. Metadata fields: _meta for internal metadata, x-* following the OpenAPI extension convention

About the SubModel alternative

This is a great suggestion! We did consider a similar design:

_anchors:
  shared_model: &default_model
    type: native
    model: "openai:gpt-4o"

However, this approach has trade-offs:

• Pros: More structured, with explicit schema support via a nested SubModel
• Cons: When referencing YAML anchors, users would need to use *_anchors.shared_model (non-standard YAML anchor syntax), which breaks the intuitive expectation of how YAML anchors typically work

The current approach preserves idiomatic YAML usage while declaring these fields via patternProperties in the JSON Schema, so YAML LSPs won't flag them as errors.

I'm happy to adjust the implementation if you prefer the SubModel approach, or we can iterate on other ideas. What do you think?